/*
 * Copyright 2012-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.boot.jdbc.metadata;

import javax.sql.DataSource;

/**
 * 提供对大多数连接池 {@link DataSource} 实现中常见的元数据访问。
 *
 * @author Stephane Nicoll
 * @author Artsiom Yudovin
 * @since 2.0.0
 */
public interface DataSourcePoolMetadata {

	/**
	 * 返回连接池的使用率，取值范围为 0 到 1（如果连接池无限制，则返回 -1）。
	 * <ul>
	 * <li>1 表示已分配最大数量的连接</li>
	 * <li>0 表示当前没有活动连接</li>
	 * <li>-1 表示连接数量没有限制</li>
	 * </ul>
	 * 如果数据源无法提供计算连接池使用率所需的信息，也可能返回 {@code null}。
	 * @return 使用率值，或 {@code null}
	 */
	Float getUsage();

	/**
	 * 返回当前从数据源分配的活动连接数，如果不可用则返回 {@code null}。
	 * @return 活动连接数，或 {@code null}
	 */
	Integer getActive();

	/**
	 * 返回已建立但处于空闲状态的连接数量。如果该信息不可用，则返回 {@code null}。
	 * @return 空闲连接数量，或 {@code null}
	 * @since 2.2.0
	 * @see #getActive()
	 */
	default Integer getIdle() {
		return null;
	}

	/**
	 * 返回可同时分配的最大活动连接数，如果没有限制则返回 {@code -1}。
	 * 如果该信息不可用，也可能返回 {@code null}。
	 * @return 最大活动连接数，或 {@code null}
	 */
	Integer getMax();

	/**
	 * 返回连接池中最小的空闲连接数，如果该信息不可用则返回 {@code null}。
	 * @return 最小空闲连接数，或 {@code null}
	 */
	Integer getMin();

	/**
	 * 返回用于验证连接有效性的查询语句，如果该信息不可用则返回 {@code null}。
	 * @return 验证查询语句，或 {@code null}
	 */
	String getValidationQuery();

	/**
	 * 此连接池创建的连接的默认自动提交（auto-commit）状态。
	 * 如果未设置（{@code null}），则使用 JDBC 驱动默认值。
	 * （如果为 null，则不会调用 java.sql.Connection.setAutoCommit(boolean) 方法。）
	 * @return 默认的自动提交状态，或 {@code null}
	 */
	Boolean getDefaultAutoCommit();

}
